Skip to content

spec(FIX-548): create-flow-state — one command to a working FSD app - #1312

Open
jhoffner wants to merge 30 commits into
mainfrom
spec/FIX-548
Open

jhoffner wants to merge 30 commits into
mainfrom
spec/FIX-548

Conversation

@jhoffner

@jhoffner jhoffner commented Aug 15, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

Someone who hears about FSD and has no project yet has nowhere to start. Adding FSD to a
repository that already exists is now agent work (FIX-1159's install skill), and that path
assumes a repository. For someone starting fresh there is no path at all short of assembling one
by hand out of our monorepo — the thing this epic exists to stop asking people to do.

Public Launch's front door is a single command, and what a stranger judges FSD by in the first
five minutes is whether that command ends at something that visibly works.

What this spec does

npm create flow-state my-app → a Next.js app with a working chat page, plus the dev command it
prints. Run that command and a real model streams into the page. Two steps, deliberately: no
comparable scaffolder starts a server for you, and the epic's proof is worded to match.

This issue is the greenfield path in every part. There is no fsdev init — FIX-1159 ships
neither the command nor a library behind it — so alongside the template this package also does the
API key, the ignore entry, the agent-instructions section, the install, and the printed next-steps
block. What stays elsewhere is authorship of two blocks of text, embedded here verbatim.

flowchart TB
  A[1 · resolve invocation<br/>name · provider · key · package manager<br/>Node ≥ 22.18] --> B[2 · create the bare app<br/>create-next-app, pinned, install skipped]
  B --> C[3 · write the template<br/>6 files · + 3 changes to files next wrote]
  C --> D[4 · append AGENTS.md section<br/>FIX-1160's block, verbatim]
  D --> E[5 · credential stop<br/>git check-ignore, then write the key]
  E --> F[6 · add the dependencies<br/>package manager add — writes the entries and resolves them]
  F --> G[7 · print next steps<br/>FIX-1159's block, verbatim]
Loading

Steps 3–4 are every deterministic write; 5 and 6 are the two whose failure is recoverable. That
order is why §9 can promise a failed install leaves a project the printed recovery actually
completes. Steps 2 and 4 can fail too and neither is recoverable — both stop the run.

Status

The spec is complete and closed. Epic §5 Q6 is answered — one starter, the Next.js chat app.
The remaining open item is epic §5 Q7 (what the unauthenticated-demo rail should do), which is
the owner's and blocks no part of this document; nothing here anticipates its answer.

Parts worth reviewing closely

  • §6 decision 3 — the five jobs, and why there is no elsewhere to send them. FIX-1159's
    Non-goals disclaim the API key, the ignore entry, the agent-instructions section, the install and
    the printed block by handing them here; this spec's Non-goals disclaimed the same five by handing
    them back. They were owned by nobody, and so was the epic's greenfield proof. Decision 3 takes
    them and prices it: the seam is gone, Size moves Small → Medium, and "byte-identical to a
    standalone init run" becomes normalized equality against canonical text.

  • §12 — the FIX-1160 edge, which this spec did not carry at all. Epic theme 9 (c) and FIX-1160
    §7 both state it from their own side. An edge asserted in two documents and enforced by neither
    does not exist
    : built from this spec as it stood, the package would have embedded nothing and
    merged before its content had an author. Now recorded, and wired in Linear (it was related, not
    blocks). Sub-PR a likewise listed no prerequisites while embedding two other issues' canonical
    text; it now names both.

  • §12 — the wiring contract is five items, not three. This spec said three and omitted how
    the provider is wired
    and the runtime floor. The omission was not cosmetic: the first is
    precisely what decision 5 then specified the opposite of.

  • §6 decision 5 is reversed, mechanism and argument both. It specified models: { default, intents, providerPreference } and explicitly rejected a concrete provider/model string; the
    wiring contract requires a statically imported provider passed as a pre-built modelResolver,
    no intents. The old rationale is not weakened but void — providerPreference only reorders
    intent candidates, and there are none — which is why it is restated as a changed decision rather
    than edited.

  • §6 decision 8 — what the generated app actually does, stated as description rather than
    promise.
    Four successive product statements about this were false, each derived from our own
    rules rather than measured. A POC then ran the real code: the guard keys on bind address not
    environment, enforces whole-app not per-flow, refuses a correctly-authenticated app as a false
    positive, and is not on this template's path at all — the symbol appears only under
    packages/node/ and packages/cli/src/commands/serve.ts, never in packages/next. So there is
    no promise here any more, only §12's description:

    • In development, npm run dev binds 127.0.0.1. The app is reachable from that machine and
      nowhere else, because we set that default in a script we authored.
    • In production, npm run build && npm start binds wherever Next binds — 0.0.0.0 by
      default — because we changed nothing about scripts.start. Nothing of ours narrows it and
      nothing of ours refuses a request.
    • The demo flow accepts any caller. It is on the framework's default resolver, which trusts a
      caller-supplied body.userId. So a deployed generated app is an endpoint that runs model
      calls for anyone who finds it, billed to the developer's provider key, with no tenant
      boundary
      — and git check-ignore keeps the key out of version control, which is a different
      problem from keeping it out of a stranger's requests.
    • What closes it is configuring real authentication, which is what the AGENTS.md section
      exists to teach. Until Q7 answers, nothing in the generated project does it for them, and this
      spec does not claim otherwise.

    This replaces a statement that said the app "does not serve off-host until authentication is
    configured — on every path the template ships and every mainstream deploy." That was false: a
    hardcoded loopback bind in a package.json script is not in a platform deploy's path, and the
    scripts.start narrowing it assumed has since been withdrawn as actively harmful — Next's -H
    carries no environment binding, so a container binds loopback, health checks never connect, and
    the app reads as dead.

  • §12 — the two demo flows are different artifacts, and the asymmetry is a rule. This template
    writes src/flows/chat/flow.ts with no credential; FIX-1159's brownfield skill writes
    flows/hello/flow.mts with one. Epic theme 8's matrix is the statement of record: a path gets
    the bind when we author the command that starts the server, and the credential when the
    demo ships no browser client to leak it. This template authors scripts.dev and ships a chat
    page — first control, not the second.

  • §7's dependency set is derived, and step 6 is what writes it. createFlowState and
    createFilesystemStores come from @flow-state-dev/engine, which the set omitted; npm hoists
    it and pnpm does not
    , so every install-backed proof was green on a manifest whose config could
    not resolve its first call. @flow-state-dev/devtool was also missing and fails on every
    manager. Then the list itself turned out to be inert — no step wrote it. Dependencies are now
    pinned from a per-package version map
    , because .changeset/config.json declares "fixed": []
    and "linked": [], so one shared placeholder would request a version that does not exist for at
    least one package. zod is pinned to a Zod 3 range: packages/core depends on zod ^3.25.76
    and types its public block surface as v3 ZodTypeAny, so a floating zod resolving to v4 fails
    next build before the app reaches a model.

  • §10 — checks are asserted on outcomes, not incantations. Pinning is asserted on the written
    manifest
    , since npm install pkg@1.2.3 persists ^1.2.3 without --save-exact. Every
    installing check runs under pnpm; the headline goal check stays npm because that is the
    advertised UX, and the pnpm run beside it is what makes that one trustworthy. The goal check runs
    interactively — -y suppresses the key prompt and there is no key flag, so the -y form
    could never have produced the streamed response §10 requires.

  • §13 — four implementer notes, and the failure mode this document actually had. The notes cover
    the version map versus a fixed release group, asserting pinning on the manifest, the standing
    prohibition on building a production refusal before Q7, and the probe's environment-dependent
    evidence. They sit under a note about the pattern: a requirement recorded in one section and
    enforced by no other
    — and its mirror, a promise withdrawn in one section and still made in
    another. Four of five withdrawal residuals were a table row, not a sentence, because a row
    states a claim as a compressed fact in a section organised by a different question, so a search
    for the withdrawn wording never finds it. When you withdraw a claim, walk the tables by reading
    the rows.

Links

Linear FIX-548 ·
epic FIX-1161 ·
blockers #1310 (FIX-1159) and
#1311 (FIX-1160) ·
spec: spec/FIX-548.md ·
POC: spec-poc/FIX-548-next-template-shape/

One open cross-issue correction — the only item where building as-written produces a wrong artifact

The withdrawn security promise still lives in FIX-1159's canonical next-steps block, which this
package embeds verbatim under a normalized-equality assertion. The text tells the user the app
"will not serve in production until you configure authentication." Both halves are false.

If it is not corrected in canonical before this issue builds, the scaffolder re-ships a false
security claim to every user, and the equality check actively prevents the shipper from correcting
it
— the mechanism built to stop drift would pin the false claim in place. This cannot be closed
from FIX-548's side by construction
; it is routed to FIX-1159 as a required correction.

Review history — what the rounds folded, and the pattern in them

The pinning fix had three defects of its own, one a build break: zod was left deliberately
floating while the FSD packages were pinned, which aimed the remaining risk at the one type boundary
the generated flow crosses on every run; one placeholder was used for six independently released
packages; and add pkg@1.2.3 was assumed to persist an exact entry, which it does not.

Before that: the scripts.start narrowing and the production refusal were withdrawn after the
rail was measured, and the withdrawal had to be chased through decision 8, a change table, the file
table, §8, §10, a §12 premise, a follow-up, §9's deployment row, and the printed success
transcript
. The dependency set was listed with no step that wrote it. Sub-PR a listed no
prerequisites. A cross-reference pointed at a §12 that did not contain the thing it named. The
AGENTS.md append ran after the install, so a failed install left a project the printed recovery
could not complete — then, once reordered, was allowed to fail and continue, which falsified the
same promises again. The goal check specified -y, which suppresses the key prompt the same run
needed answered — a check that could not pass, the mirror of the class that dominated every
other round.

Every finding against the POC has been one defect class: a check whose result does not correspond
to the claim it is cited for
— in three directions. Cannot fail: a marker count surviving a
truncated section; a green npm install hiding a missing @flow-state-dev/engine; an ordering
assertion staying green when the step it ordered ran and failed. Cannot pass: the -y goal check.
Fails for the wrong reason: git init's discarded exit status, and inherited NODE_NO_WARNINGS
suppressing the very diagnostic a check reads — both reporting a true claim as disproved,
which is the direction that teaches people to stop believing red results.

probe.sh is frozen — and the freeze was lifted exactly twice, both under the same standing
clause
: a finding that the script reports a true claim as disproved is fixed in the script;
everything else is narrowed in the README. The rule covers over-assertion, and both of those were
under-reporting in the one direction that cannot be documented away.

For automated reviewers — what this PR is and how to review it

This is a spec PR. It carries one Markdown file under spec/ (plus a throwaway POC under
spec-poc/, which CI ignores) and is never merged — it closes unmerged once the spec is
approved, and the branch is kept so the reviewed copy stays fetchable (BP-037). There is no
production code to review.

This spec is approved and closed. Findings that would change the approach are no longer being
folded; genuine issues belong in §13 as implementer notes.

Review the direction, not the prose:

  • Does the approach solve the stated problem, and is it the smallest thing that does?
  • Are the decisions in §6 actually decisions, with the rejected option named and the consequence of
    being wrong stated?
  • Are the verified premises in §12 true? They are read from the code, or measured by the POC —
    check them.
  • Does every requirement have something that enforces it? Several defects in this spec's history
    were requirements stated in one section and enforced by no step, test, or tracker edge — and
    promises withdrawn in one section and still made in another. §13 opens with that pattern.

The bar: a spec is approved when it is directionally correct, not when nothing is left to
nitpick (BP-040).

probe.sh is frozen — findings against the POC are answered by narrowing a README claim to what
the frozen script proves, not by changing the script. The one exception, and the reasoning for it,
is recorded in the POC README: a finding that the script reports a true claim as disproved is
fixed in the script.

…ojects

Scopes the wrapper to the two things neither create-next-app nor `fsdev init`
can produce: a demo flow and the chat page that talks to it. Everything else —
detection, config, host wiring, credentials, install, next-steps — stays init's.

Settles the init handoff as a library call rather than a subprocess (a
subprocess cannot be handed the answers already collected, so it asks for the
API key twice), declines to maintain a Next.js skeleton, and unblocks the issue
from FIX-1162 by publishing under the scope we already own.

Raises one ask: whether the Node API template ships at all, now that FIX-1159
generates no server file and adds no package script.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
@linear-code

linear-code Bot commented Aug 15, 2026

Copy link
Copy Markdown

FIX-548

@vercel

vercel Bot commented Aug 15, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated (UTC)
flow-state-dev-docs Ignored Ignored Aug 19, 2026 11:44am
flow-state-dev-kitchen-sink Ignored Ignored Aug 19, 2026 11:44am
flow-state-dev-ui Ignored Ignored Preview Aug 19, 2026 11:44am

Comment thread spec/FIX-548.md Outdated
Comment on lines +70 to +71
breaks loudly and in public, which is the redeeming feature; we pin a tested major range
and treat it as a patch-level fix.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Scaffolder version pin is undefined

When a newer create-next-app release changes its flags, prompts, or generated layout, the unspecified invocation resolves that untested version, causing project creation to hang, reject the arguments, or write the demo page outside the served layout. Define how the promised tested major range is enforced; the stubbed CI tests cannot detect upstream version drift.

Fix in Cursor

Comment thread spec/FIX-548.md Outdated
Comment on lines +449 to +450
**cwd-only**. There is no directory scan that would pick a flow up on its own, which is why
init must be *told* the demo flow's name rather than discovering it.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Flow discovery premise is inaccurate

The statement that no directory scan can discover a flow overlooks discoverFlows, which scans conventional flow directories when no config is available. Distinguish that discovery path from the generated-config path, where explicit registration is still required, so implementers do not inherit an inaccurate model of CLI resolution.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Fix in Cursor

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify review — direction sound, a few seams worth trimming

This is a spec-only PR, so the question is whether the approach is the smallest thing that solves the problem. On that bar: yes, mostly. The spec is unusually honest about its own weakness (two commands almost work; epic theme 1 tripwire; three authored files). Delegating the bare app to create-next-app (install skipped) and everything else to fsdev init is the right decomposition. Decision 5 (no hello-chat UI port) and the ordering invariant (demo content before init) are load-bearing and well argued.

What pushes complexity past "thin wrapper" is mostly cross-package contract and v1 futures, not the product surface:

Where the approach may have gone further than necessary

  1. In-process init library call (§6.1 / §7) — The double-prompt problem is real, but the chosen fix expands FIX-1159's public surface (four-row seam + returned next-steps string) before that issue has landed. A lighter alternative worth weighing on #1310: non-interactive fsdev init via subprocess with flags/env for provider, key, cwd, supplied-flow path, and -y. Same UX (one prompt collection), smaller API, matches how fsdev ui already delegates via npx. If library-first is already committed on #1310, fine — but the subprocess path is dismissed without exploring init CLI passthrough.

  2. --template in v1 with a single legal value (§6.4, §9) — YAGNI for a one-template release. Hardcode Next.js chat; add the flag when node-api (or a second host) actually ships. Saves validation, refusal table row, and CI behaviour for a one-value enum.

  3. Byte-identical next-steps assertion (§10) — Brittle cross-package coupling on presentation bytes. Prefer: same ordered commands/URLs (normalized), or snapshot owned by init with create-fsd-app only asserting init was called once and printed its marker block.

  4. Generated layout diverges from published docs (§7) — Spec places the flow at flows/chat/flow.ts and examples use fsdev run chat send, while quick-start / project-structure use src/flows/hello-chat/flow.ts and fsdev run hello-chat chat. A greenfield user will hit the docs immediately after scaffold — this drift is the highest-impact implementer fix. Recommend aligning with src/flows/hello-chat/ + hello-chat/chat naming, and citing quick-start §5 as the page source (not hello-chat's page).

  5. Spec bulk — Decision 4 is argued twice (§6 item 4 + "The ask"). §12 "Verified premises" (~25 lines) re-closes PR #1301 notes the implementer inherits from merged init. Two sub-PRs for "3 files · ~9 tests" may cost more process than it saves unless publish isolation is mandatory.

What I'd keep as-is

  • Single install via CNA --skip-install → init install once.
  • Refuse-before-create / no rollback after partial failure.
  • Goal check without pre-exported API key.
  • One Next.js template recommendation (decision 4) — the FIX-1159 hollowing argument is persuasive.
  • Stubbed CI for ordering/seam + real goal check for product proof.

Performance

Not a concern for a one-shot scaffold. Dominant cost is CNA + install; spec already guards against double install.

Verdict

Direction: approve-worthy after a light trim pass — not blocking on prose, but I'd resolve (4) path/naming alignment and either justify (1) library-over-subprocess on #1310 or document why CLI passthrough was rejected. Items (2)–(3) and spec bulk are implementer-friendly cuts that would make the eventual code change smaller.

Happy to converge in round 2 once path alignment and the init seam shape are settled.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread spec/FIX-548.md Outdated

### 6. Decisions & rules — the sign-off surface

1. **`create-fsd-app` calls `fsdev init` as a library, in the same process — not by shelling

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplification fork: subprocess init is rejected because credentials can't be handed across. That's true for a default npx @flow-state-dev/cli init, but not necessarily for init with --provider, --api-key, --cwd, --flow-module, -y (or env equivalents).

Library-in-process is defensible, but it forces four rows of public API on FIX-1159 (#1310) before that seam exists. Worth an explicit "we considered CLI passthrough" sentence with why it loses — otherwise implementers may build the heavier seam when a flagged subprocess would suffice.

Comment thread spec/FIX-548.md Outdated
*This one reverses an epic theme and is the ask on this PR — see the framing below.*
*Rejected:* two templates, as epic theme 2 decided.
*Locks in:* one starter to keep green on machines we do not control, and one goal-check run
per release instead of two. The `--template` flag still ships with one value, so adding

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

YAGNI: v1 has one template but still ships --template, a refusal row (§9), and CI coverage for unknown templates. Consider hardcoding Next.js chat in v1 and adding the flag when a second template exists — same product, less surface.

Comment thread spec/FIX-548.md Outdated
cd my-app
npm run dev your app → http://localhost:3000
npm exec fsdev dev the FSD DevTool → http://localhost:4200
npm exec fsdev run chat send --input '{"userId":"u1","message":"hi"}'

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Naming drift vs repo/docs: quick-start and project-structure use hello-chat kind + chat action (fsdev run hello-chat chat …). This example uses chat/send. Recommend aligning the generated project with existing docs so the post-scaffold docs path is frictionless.

Comment thread spec/FIX-548.md Outdated

| file | what it is |
|---|---|
| `flows/chat/flow.ts` | the demo flow — one action, one streaming generator. `examples/hello-chat`'s flow is the reference for shape, not for size |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Path drift: published docs use src/flows/hello-chat/flow.ts (quick-start, project-structure, your-first-flow). Spec puts flows/chat/flow.ts at project root. CNA's default src/ layout + docs alignment suggest src/flows/<name>/flow.ts unless FIX-1159 init hard-codes a different path — in which case all three should agree.

Comment thread spec/FIX-548.md Outdated
| provider and key | already collected in step 1; a second prompt is decision 1's whole subject |
| the demo flow's name and module path | init's generated config imports and registers it, **and authors no flow of its own** (epic theme 1). Without this input, init writes `flows/hello/flow.ts` beside the advertised one and the wrapper's only exits are overwriting or deleting a file init just wrote |
| the package manager | one manager, one lockfile |
| **returned:** the next-steps block | printed once, by init, byte-identical to a standalone init run (epic theme 5) |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Brittle contract: "byte-identical" next-steps (also §10) couples create-fsd-app CI to init wording. Any init copy tweak breaks wrapper tests though behaviour is fine. Consider asserting same commands/URLs in order (normalized whitespace) or owning the snapshot in init's test suite only.

Comment thread spec/FIX-548.md

---

#### The ask — does the Node API template ship?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Decision 4 is argued here (~40 lines) and again in §6 item 4. Fine for the epic-owner gate in Part I, but Part II could reference the approved outcome once — reduces spec bulk without losing the ask.

Comment thread spec/FIX-548.md
*Depends on:* 1, 2, 3, **and FIX-1159's library seam existing.**
5. **Publish configuration and the README that renders on npm.** *Depends on:* 1.

**PR plan.** Two sub-PRs.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two sub-PRs for a package described as "3 authored files · ~9 tests · 2 PRs" — is the split buying anything beyond publish isolation? If not, one PR (code + README + docs + changeset) may be simpler to review and ship.

Comment thread spec/FIX-548.md Outdated
step 2 does for one template and whether §10 records one goal run or two; it changes nothing
else.

**Verified premises** (read from the code and from FIX-1159's spec, so a reviewer need not

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

§12 verified premises are reviewer-defense (PR #1301 note closure, hello-chat shape disclaimer). Useful in spec review; consider moving resolved-upstream notes to §13 or trimming to 3–5 bullets the implementer must re-check at merge time (e.g. init has no library export yet, cwd-only config search).

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0a031eb7f2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md Outdated

| file | what it is |
|---|---|
| `flows/chat/flow.ts` | the demo flow — one action, one streaming generator. `examples/hello-chat`'s flow is the reference for shape, not for size |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Align the demo model with the selected provider

When a user selects Anthropic or Google, this reference can produce a scaffold that installs and configures that provider but whose first message still fails: examples/hello-chat/src/flows/hello-chat/flow.ts:19 hard-codes openai/gpt-5-mini, while the spec never requires replacing it with intent/chat or a model derived from the selected provider, and the single goal run would not expose the other-provider path. Make provider-neutral model resolution an explicit template contract and verify every offered provider, or restrict the prompt to OpenAI.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
Comment on lines +332 to +333
| a | the package: invocation surface, bare-app step, demo content, init handoff (steps 1–4) | — |
| b | publish configuration, package README, and the three doc surfaces in §11 (step 5) | a |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Keep package implementation and documentation in one PR

When sub-PR a lands, the new public package and command exist without their package README, onboarding docs, or publish configuration because all of those are deferred to sub-PR b. That creates an intentionally stale public surface between merges and violates the repository requirement to update API documentation in the same change set; combine these deliverables or include the required documentation in the package PR.

AGENTS.md reference: AGENTS.md:L197-L205

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
Comment on lines +91 to +92
5. **The demo chat page adds no user-interface dependencies. One file, `@flow-state-dev/react`,
and nothing else.**

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Move engineering choices out of owner sign-off

When the product owner reviews §6, they are asked to ratify five decisions, including implementation mechanisms such as in-process invocation, scaffolder flags, and UI dependency selection; those are implementer calls rather than business forks, and only the template/package outcomes need owner sign-off. Move decisions 1, 2, and 5 into the technical design so the sign-off surface stays focused on decisions the owner actually owns.

AGENTS.md reference: AGENTS.md:L54-L58

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

From FIX-1162 (spec PR #1313) — your decision 3 rests on two things that are not true. Raising while this spec is still in review, since both are cheap to fix now and a re-spec later.

The unscoped create-fsd-app cannot be secured. Decision 3 says it "becomes an alias if and when FIX-1162 secures it." It has belonged to an unrelated project since 2024 (9 versions, last published 2024-10-18), so there is no version of FIX-1162 that secures it. Verified against registry.npmjs.org on 2026-08-15.

FIX-1162's decision 2 proposes create-fsdev-app for the short name — verified free — and suggests renaming this spec's scoped package from @flow-state-dev/create-fsd-app to @flow-state-dev/create-fsdev-app so the canonical name and its eventual alias carry one brand instead of two. The fsd stem is a bad bet generally: fsd, fsd-cli, fsdev-cli and create-fsd are all taken, largely because FSD is an established abbreviation for Feature-Sliced Design. Fallbacks if npm's similarity check refuses create-fsdev-app at publish time, all verified free: create-flow-state-app → create-flowstate-app → create-flow-state-dev-app.

"the scoped name we already own" is unverified. Nothing under @flow-state-dev/ has ever been published — cli, core, engine, react, contracts all 404 — and whether the flow-state-dev npm organization is registered to us cannot be checked without the account. An npm scope goes to whoever registers the matching organization first. FIX-1162's decision 1 is to register it, which is free and needs no publish; until that happens, the sentence asserts something nobody has checked. Nothing in your design changes — only the confidence the sentence expresses.

Neither point touches this spec's approach. Decision 3's shape — ship scoped, alias short later — is the one FIX-1162 builds on rather than reverses.


Generated by Claude Code

@jhoffner jhoffner added the spec label Aug 15, 2026
…end to end

Three owner/coordinator decisions landed after this spec was written. Not a
review round; re-drafted rather than annotated, and the spec returns to the gate.

1. The greenfield/brownfield split. Brownfield is an agent skill, so the
   wrapper-over-init architecture this spec was built on is gone and the epic's
   re-drafted theme 1 gives this issue its template end to end. §6 decision 3
   moves the config and the Next mount here as checked-in files; §7's seam to
   init shrinks to credentials, the AGENTS.md section, the install, and the
   printed block.
2. One template. The Node API template is cut from v1; the ask is re-argued on
   the asymmetry (adding later is additive, removing later is not) rather than
   on file count. Decision 2b drops the `--template` flag with it — a flag with
   one legal value documents an intention and does nothing.
3. The package is `create-flow-state`, published unscoped, which removes
   FIX-1162 as a gate by any route rather than by a workaround.

A POC settled the shape the re-draft turns on. Owning the template means owning
the config file, which has two consumers at once — Turbopack and the CLI's
native import() — and nobody had checked the first. Against a real
create-next-app@16 project: Turbopack will not resolve an extensionless import
to .mts, TypeScript rejects the explicit .mts specifier without
allowImportingTsExtensions, and fsdev.config.ts with "type": "module" builds,
serves, and loads warning-free. It also found that create-next-app writes its
own AGENTS.md (own delimiters, re-added by next dev) and a CLAUDE.md, that its
.gitignore already carries .env*, and that unpassed flags resolve from saved
preferences. So the greenfield path appends to an agent-instructions file — a
case the epic had filed under brownfield.

Three earlier findings carried forward rather than lost: the credential hazard
became decision 7 plus an executed `git check-ignore` assertion, provider/model
alignment became decision 5's intent map with the goal check run per provider on
a single key, and every printed command is asserted by running it.

Both Greptile findings from the previous round folded inline (factual, no round
spent): the create-next-app pin is now concrete, and the flow-discovery premise
now states that directory discovery exists and is the no-config fallback.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
@jhoffner jhoffner changed the title spec(FIX-548): create-fsd-app — npx-able scaffolding for new FSD projects spec(FIX-548): create-flow-state — one command to a working FSD app Aug 18, 2026

Copy link
Copy Markdown
Collaborator Author

Re-drafted against three decisions that landed after this spec was written (3118cce). Not a review round — the spec is not approved and returns to the gate. Description rewritten to match.

What changed and why

  1. The greenfield/brownfield split. The wrapper-over-init architecture this spec was built on is gone — there is no deterministic brownfield command to be a thin wrapper over. The epic's re-drafted theme 1 gives this issue its template end to end, so §6 decision 3 moves the config, the mounted route, the demo flow and the page here as checked-in files, and §7's seam to init shrinks from four rows to five inputs and one return: credentials, the AGENTS.md section, the install, and the printed block. I read "owns end to end" as checked-in, not assembled at runtime, because theme 1's replacement tripwire is drift and instructions can only point at a shape a person can read. That reading is the biggest thing to push back on.
  2. One template. The Node API template is cut from v1 and the ask is re-argued on the asymmetry rather than on file count. Decision 2b drops the --template flag with it — a flag with one legal value documents an intention and does nothing; a refusal listing a single value reads worse than no such flag, and adding a flag nobody could have been passing breaks no invocation.
  3. create-flow-state. Published unscoped, npm create flow-state my-app. This removes FIX-1162 as a gate by any route rather than by the previous draft's scoped-name workaround, and makes FIX-1162's "create-fsd-app is unobtainable" finding stale — §12 raises that rather than editing the sibling.

A POC settled the premise the re-draft turns on (spec-poc/FIX-548-next-template-shape/, bash probe.sh, ~2 min). Owning the template means owning fsdev.config.*, which has two consumers at once — Turbopack and the CLI's native import() — and nobody had checked the first. Against a real create-next-app@16 project: Turbopack will not resolve an extensionless import to .mts, TypeScript rejects the explicit .mts specifier without allowImportingTsExtensions, and fsdev.config.ts with "type": "module" builds, serves, and loads warning-free. So the template diverges from FIX-1159 decision 4 on the same filename, for a measured reason, and §12 raises it there.

It also found four things nothing in this epic knew: create-next-app writes its own AGENTS.md (own delimiters, re-added by next dev) and a CLAUDE.md; its .gitignore already carries .env*; and unpassed flags resolve from saved preferences, so every flag has to be explicit and --yes is not a substitute. The first matters most — the greenfield path appends to an agent-instructions file, it never creates one, a case the epic files under brownfield.

Earlier review findings carried forward, not lost. The credential hazard became decision 7 plus an executed git check-ignore assertion rather than an assumption about someone else's .gitignore. Provider/model alignment became decision 5's intent map, with the goal check run per advertised provider, single key only. Every printed command is asserted by running it, which is what catches npm's -- separator. And the fsdev serve hazard is recorded in §12 with the correction that its default port is 3000, not 8787 as the epic's Node transcript shows — it belongs to the template decision 2 cuts, so it is a note rather than a design element here.

Both Greptile findings from the previous round are folded (factual corrections, no round spent):

  • Scaffolder version pin undefined — valid. §7 step 2 now pins the version in the spawned specifier, held in one constant, asserted in the argv test, and §9 states plainly that nothing stubbed can detect upstream drift, so the goal check is the detector and the pin is what keeps the gap off users' machines in between.
  • Flow discovery premise inaccurate — valid. §12 now says directory discovery (src/flows/, flows/) exists and is the no-config fallback; once a config resolves, the explicit registry is what serves, which is why the template registers its flow.

The one ask is unchanged in substance and re-argued: does the Node API template ship? It reverses epic theme 2, so it is the epic owner's call. Recommendation: ship one.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3118cce038

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md Outdated
Comment on lines +323 to +325
**The version is pinned in the spawned specifier, not left to `npx` to resolve.** The command is
`create-next-app@<tested major>`, held in one constant in this package and bumped as a deliberate
change with a goal-check run behind it — never a bare `create-next-app`, which resolves whatever

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Pin create-next-app to the exact tested version

Using create-next-app@<tested major> still resolves the newest release within that major on every invocation. If Next changes a flag or generated layout in a minor or patch release, users immediately receive the untested version, contradicting the stated guarantee that upstream changes cannot reach them until this package is deliberately bumped. Store an exact tested version rather than only the major.

Useful? React with 👍 / 👎.

Comment on lines +105 to +108
case "$BODY" in
"$MARKER":200) echo " PASS — the route served this run's config module" ;;
*) echo " FAIL — expected $MARKER:200" ;;
esac

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Return failure when the endpoint proof fails

When next dev fails to start or /api/flows returns the wrong response, this branch only prints FAIL; the unconditional exit 0 later still reports a successful POC run. That allows automation or a reviewer relying on the exit status to accept the central served-route claim when it was not proven, so the mismatch and the no-free-port path should terminate unsuccessfully.

Useful? React with 👍 / 👎.

claude added 2 commits August 18, 2026 00:22
…r provider

The per-provider rule in §10 made "one recorded run, or two" wrong: the proof
is three runs for one template and six for two. §6's trade-off, §10's opening
and §12's open question now all say the same number, which matters because that
count is the cost the ask is pricing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
…hen it fails

Both from Codex's review of 3118cce, folded into the rework in flight.

P1 — the major-range pin did not hold the guarantee the spec makes. Codex is
right: `create-next-app@16` re-resolves to the newest 16.x on every invocation,
so a Next minor that moves a flag or the generated layout reaches users the day
it ships, while §7 claimed upstream changes cannot reach them until we bump. The
pin is now an exact release, the argv assertion rejects a range as well as a
missing pin, and §9 gains the cost that makes this honest: create-next-app
writes an exact `next` version into the manifest it generates, so pinning the
scaffolder also pins the Next version new projects start on. Bumping it is
scheduled maintenance behind a goal-check run, not a rare event. The probe is
pinned exactly for the same reason — it is cited as evidence, so a reader
running it later must get the version the findings were measured on.

P2 — dropped by the stated contract, taken anyway, because the reasoning is
right. The probe printed FAIL and exited 0, which is a check able to report
green for a claim it did not prove — the failure BP-003 and tenet 7 name, and
the same one the per-run marker and free-port check were added to close. The
served-route and AGENTS.md checks are now assertions: exit 0 they held, 1 one
failed, 2 could not be checked. Verified in both directions — a full run passes
(`probe: PASS`, exit 0), and the verdict logic returns 1 for a stale marker, a
non-200, an empty body, a missing FSD section, and a duplicated next block.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m

Copy link
Copy Markdown
Collaborator Author

@codex — both folded in dbda62f, inside the rework rather than as a review round.

P1 (pin an exact version, not a major) — you're right, and it was the spec failing against its own mechanism. §7 claimed upstream changes cannot reach users until we deliberately bump, and create-next-app@16 re-resolves to the newest 16.x on every invocation, so that claim was false as written. Now:

  • the specifier is an exact release (create-next-app@16.3.1), held in one constant;
  • §10's argv assertion rejects a range as well as a missing pin, since @16 is the failure mode that looks pinned;
  • the probe is pinned exactly too — it is cited as evidence, so a reader running it in six months has to get the version the findings were measured on.

One thing your comment prompted that I'd have otherwise left implicit, and it makes the trade honest rather than free: create-next-app writes an exact next version into the manifest it generates, so pinning the scaffolder also pins the Next version new projects start on. An exact pin therefore buys the guarantee at the price of a starter that drifts behind current Next unless we bump it. §7 and §9 now say that plainly — bumping is scheduled maintenance gated on a goal-check run, not a rare reaction to breakage. That is the right trade (a starter a few months behind beats a starter that breaks without warning), but it should be a decision a reader can see, not a side effect.

P2 (probe printed FAIL and exited 0) — dropped by the contract, taken anyway, because your reasoning is right. An exit-0-on-failure in the script that is the evidence for the served-route claim is the same failure class as the two things already fixed in this probe: it uses a fresh marker per run on a port it proves free first, precisely because an earlier version reported green by reaching a stale dev server left over from a previous run. Exiting 0 on a mismatch would have let that back in through the front door. So:

  • the served-route and AGENTS.md checks are assertions now — 0 they held, 1 one failed, 2 could not be checked (no free port), with the contract stated in the README;
  • verified in both directions, not just the happy one: a full run passes (probe: PASS, exit 0), and the verdict logic returns 1 for a stale marker, a non-200, an empty body, a missing FSD section, and a duplicated Next block.

For the record on the contract itself: the "line-level POC feedback is dropped" rule exists so nobody spends attention on code that isn't shipping. A POC whose exit status is load-bearing for a claim in the spec isn't line-level — it's the evidence, and evidence that can't fail is worth what it cost. Fair catch.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dbda62f06d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md Outdated
| `fsdev.config.ts` | default-exports `createFlowState({ flows, models, stores })`. Registers the demo flow explicitly, declares decision 5's intent map with the chosen provider's model as `default`, and declares FIX-1159 decision 5's development file store, qualified as such |
| `lib/flowstate.ts` | re-exports the config's default as `flowstate`. Reconciles the CLI (which searches the project root for `fsdev.config.*`, cwd-only) with the routes (which import through the `@/` alias). Both in-repo examples do this; the published quick-start does not, and §11 fixes that |
| `src/flows/chat/flow.ts` | the demo flow — one action, one streaming generator, model `intent/chat`. `examples/hello-chat`'s flow is the reference for shape, not for size. Path matches what the docs teach |
| `app/api/flows/[...path]/route.ts` | `createNextHandler(flowstate)` from `@flow-state-dev/next` — the platform-agnostic adapter, one line, no Vercel assumption |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Preserve dynamic streaming on the catch-all route

When the generated app sends an action, the SSE request goes through this catch-all route, but the specified one-line template omits export const dynamic = "force-dynamic". The canonical packages/next/README.md example includes that export, and examples/hello-chat/app/api/flows/[...path]/route.ts documents it as required to prevent Next.js from buffering streamed tokens. The POC also sets it on the only route it exercises, so its successful result does not validate the route shape specified here; include the canonical route exports and verify a streamed response through the catch-all.

Useful? React with 👍 / 👎.

Comment on lines +72 to +73
npx next build 2>&1 | grep -E "error TS|Module not found|Failed to|Compiled successfully|✓ Compiled|Route \(app\)" | head -5
node -e "import('./$2').then(m=>console.log(' native import: OK',m.default.marker)).catch(e=>console.log(' native import: FAIL',e.message))" 2>&1 | grep -E "native import|MODULE_TYPELESS" | head -3

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Propagate build and import failures from each probe variant

When next build or the native config import fails, these commands merely print filtered output: the pipeline discards the build's status, and the import's .catch() logs FAIL but resolves successfully. The final RC only reflects the served-route and AGENTS checks, so the probe can exit 0 even when the chosen shape no longer builds or cannot be imported—the two claims the spec cites this POC to establish. Although the final endpoint now updates RC, the current lines are fresh evidence that the build/import half remains non-failing; accumulate these results into the exit status as well.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
| Target directory exists and is not empty | Refuse, naming the path. |
| Project name is not a valid npm package name | Refuse, saying which rule failed, and offer the sanitized form. |
| Node runtime below the floor the generated project needs | Refuse, with the same floor and the same message init uses. Do **not** narrow the package's `engines` below the repo-wide `>=22` — FIX-1159 §9 records why. |
| `.env.local` would be written and git would not ignore it | Add the ignore entry first; if it cannot be added, refuse before the key is written (decision 7). |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Classify ignore verification as a partial-scaffold failure

When the generated .gitignore is absent, unwritable, or cannot be verified, this check can only happen after create-next-app has already created the target and supplied the file being inspected. It therefore cannot satisfy the surrounding requirement that every refusal leaves the disk untouched, while deleting the scaffold would contradict the later no-rollback rule. Move this case into the partial-scaffold failure taxonomy, or define a genuinely pre-creation check, so the implementer is not required to meet mutually exclusive outcomes.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector

Copy link
Copy Markdown

The rework resolves both findings.

No additional changes were necessary, so I did not create a commit or follow-up PR.

Checks

  • ✅ git show dbda62f:spec-poc/FIX-548-next-template-shape/probe.sh | bash -n
  • ✅ git show dbda62f:spec-poc/FIX-548-next-template-shape/probe.sh | rg -n 'create-next-app@16\.3\.1|exit 2|RC=1|exit "\$RC"'
  • ✅ git show dbda62f:spec/FIX-548.md | sed -n '321,344p;423,430p;476,484p'

View task →

…tegory, probe accumulates

Spec-review round 1 on the reworked document. All three findings folded; none
was below the bar.

P1 — the catch-all template omitted `export const dynamic = "force-dynamic"`.
Verified against both cited files: packages/next/README.md ships
createNextHandler alongside `runtime = "nodejs"` and `dynamic = "force-dynamic"`,
and examples/hello-chat documents why — without it Next may buffer the response
body, which turns token-by-token streaming into one delivery at the end. That is
the epic's headline outcome failing while every wiring check passes. Both route
files now carry the canonical exports, §10 asserts them, §12 records the premise
(including that the Vercel quick-start's `maxDuration` is deployment-shaped and
stays out), and the goal check now requires the response to render
*incrementally* — the only check anywhere that can catch a missing force-dynamic.

The second half of that finding was the sharper one: the POC set force-dynamic
on the only route it exercised, so its green did not validate the specified
shape. The probe now writes both route files with the canonical exports and
asserts the catch-all serves a nested path, not just the bare route.

P2 — probe.sh discarded `next build`'s status through a pipeline and let a
rejected import() resolve, which are exactly the two claims §7 and §12 cite this
POC to establish. Each variant now declares the outcome the README claims for it
and a disagreement fails the probe, so "the build failed" is not automatically a
failure (two variants are supposed to fail) but "the build did something other
than documented" is.

That change immediately caught a defect in the probe itself rather than in the
finding: the first accumulating run exited 1 on the `.ts, no type field` row,
because the import check called process.exit(0) in .then() and cut off
MODULE_TYPELESS_PACKAGE_JSON before Node flushed it — the warning is emitted
asynchronously. Isolated and confirmed (exit(0): 0 warnings captured; exitCode:
1). Fixed by setting process.exitCode and letting the process drain. A probe
that could not fail would have recorded "clean" for the one variant whose whole
purpose is to warn.

Full run after the fix: all five variants match, both routes serve this run's
marker, `probe: PASS`, exit 0.

P2 — §9's .gitignore case asked for two mutually exclusive outcomes: it sat under
"refusals leave the disk untouched" but can only run after create-next-app has
created the target and written the file, and deleting the scaffold to qualify
would contradict the no-rollback rule below it. It is now its own category, the
credential stop, with the contradiction named so it is not reintroduced: the
scaffold stays, the key is not written, and the remediation is printed. §10 gains
the matching assertion; the taxonomy paragraph now describes three categories.

Not re-done, already folded in dbda62f and confirmed by the reviewer: the exact
create-next-app pin, and the probe's endpoint/no-free-port exit paths.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m

Copy link
Copy Markdown
Collaborator Author

@codex — all three folded in ecce07d. Probe exit code: 0 (probe: PASS), and the run that got there is the interesting part.

P1 — force-dynamic on the catch-all. Confirmed against both files, folded. packages/next/README.md:22-24 ships createNextHandler(flowstate) with runtime = "nodejs" and dynamic = "force-dynamic"; examples/hello-chat/app/api/flows/[...path]/route.ts carries it with the reason in a comment. My §7 said "one line", which was wrong. Both route files now carry the canonical exports, §10 asserts them on the generated files, and §12 records the premise — including that the published Vercel quick-start's maxDuration = 300 is deployment-shaped rather than correctness-shaped, so the template takes the two from the platform-agnostic README and leaves that one to whoever deploys.

The failure mode is why this was above the bar on its own, and it's now written into §10: without force-dynamic the wiring is right, the response is right, and only the timing is wrong. No stubbed check can see that. So the goal check now requires the response to render incrementally, not merely to render — that is the only assertion anywhere that would catch it.

Your second half was the sharper point, and it was right. The probe set force-dynamic on the one hand-made bare route it exercised, so its green spoke to a shape the spec does not specify. It now writes both files with the canonical exports and asserts the catch-all serves a nested path:

GET /api/flows              -> served-21908-1787013327:200
GET /api/flows/sessions/abc -> served-21908-1787013327:catchall:sessions/abc:200

P2 — build and import statuses now feed the exit code, and doing it caught a defect in the probe rather than in the finding. Each variant declares the outcome the README claims for it, so "the build failed" is not automatically a probe failure (two variants are supposed to fail) but "the build did something other than documented" is.

The first accumulating run exited 1 on the .ts, no type field row: reported clean, README claims warn. The cause was my instrumentation — the import check called process.exit(0) inside .then(), and MODULE_TYPELESS_PACKAGE_JSON is emitted asynchronously, so the exit cut it off before Node flushed it. Isolated it directly:

with exit(0):   0 warnings captured
with exitCode:  1 warning captured

Fixed by setting process.exitCode and letting the process drain. Worth stating plainly: a probe that could not fail would have recorded "clean" for the one variant whose entire purpose is to warn, and the README table would have been wrong in the direction that flatters the chosen option. That is the argument for your P2 better than I could have made it.

Full run after the fix — five variants all matching, both routes serving, probe: PASS, exit 0.

P2 — the .gitignore contradiction. You're right, and it was mine to create. The check can only run once create-next-app has made the directory and written .gitignore, so it could never satisfy "refusals leave the disk untouched", and deleting the scaffold to qualify would contradict the no-rollback rule directly below it. Rather than move it into the failure taxonomy (where it also doesn't belong — it isn't a failure, and the usual outcome is that the entry is already there), it is now its own category, the credential stop, with the contradiction named in the spec so it doesn't get reintroduced:

  • ordinary path — add the ignore entry, then write the key; create-next-app's .gitignore already carries .env*, so this is an assertion that it's true;
  • entry cannot be established — stop before the key is written, leave the scaffold usable, print the missing line and the command to finish. Never "write it and warn": the warning scrolls away, the credential doesn't.

§10 gains the matching assertion, and the taxonomy paragraph now describes three categories and why the middle one exists.

Not re-done, per your correction: the exact create-next-app pin and the probe's endpoint / no-free-port exit paths were already in dbda62f.


Generated by Claude Code

…an inherited ownership claim

The spec already said "published unscoped", so the mechanical fix was a no-op —
but it argued the name as brand fit, which left the scoped form looking like a
harmless fallback. It is not, and that gap is what this fixes.

Measured, not assumed: `npm create <name>` resolves to the UNSCOPED
`create-<name>` — `npm create flow-state-nonexistent-xyz123` requests
registry.npmjs.org/create-flow-state-nonexistent-xyz123. A scoped publish claims
nothing outside its scope, so a scoped-only package would leave this spec's
headline command resolving to a package that does not exist. Decision 1 now
carries that reasoning, and rejects the scoped-plus-unscoped-alias compromise:
it works, but nobody would ever be told to type the scoped form, so the second
package exists only to be unused (tenet 3). One package.

§12 carries the publish as a hard dependency and separates what is established
from what is not, because the same assumption has already been wrong once:

- Verified against the registry today: create-flow-state, flow-state-app,
  flow-state, fsdev and @flow-state-dev/cli all 404. Nothing in this project has
  ever been published.
- Asserted, not verified: that the name is ours. npm has no reservation
  mechanism — a name is claimed by publishing — so this cannot be confirmed from
  outside until we publish. The coordinator has it with the owner.
- Corrected: `create-fsd-app` is NOT ours. create-fsd-app@1.1.2 exists, published
  2024-10-18 by an unrelated maintainer (keyready), a React/Vite starter. The
  brief I was working from said the owner had acquired it; that does not survive
  checking. FIX-1162's original finding stands, and only the choice of name moved.

No fallback is designed for the name being unobtainable, per the coordinator's
direction — a contingency there would spread through §5, §6, §7, §9 and §11 to
hedge a question that gets answered before anything is built.

Also names the one thing an implementer would otherwise get wrong by following
convention: this package's manifest `name` is the bare `create-flow-state`, the
only unscoped package in the repo, and the directory name does not set it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
@chatgpt-codex-connector

Copy link
Copy Markdown

Outcome

The requested follow-up is already fully addressed in ecce07d1; no additional code or documentation changes were necessary.

The repository is clean, so I did not create an empty commit or a redundant follow-up PR. This complies with the requirement not to call make_pr when no changes were made.

Testing

  • ✅ export PATH=/root/.nvm/versions/node/v22.22.2/bin:$PATH; node --version; bash spec-poc/FIX-548-next-template-shape/probe.sh — exited 0 with probe: PASS; all five variant outcomes matched, and both routes returned the expected run-specific marker.
  • ✅ git diff --check f56c6b216ebca2532fb56ff6d56f6fe485500162..HEAD
  • ✅ git status --short --branch — clean working tree on work at ecce07d1.
  • ⚠️ bash spec-poc/FIX-548-next-template-shape/probe.sh under the environment’s initially active Node v20.20.2 — native TypeScript imports are unsupported there, so the import rows correctly caused probe: FAIL; rerunning with the repository-required Node 22 passed.

View task →

Copy link
Copy Markdown
Collaborator Author

Naming correction folded in c67c063 — one package, unscoped create-flow-state, as directed. Two notes, one of which is a correction going the other way.

The mechanical part was already right; the reasoning was not. The spec has said "published unscoped" since the re-draft, so nothing about the plan changed. What was wrong is that decision 1 argued it as brand fit — which is exactly what leaves a scoped fallback looking harmless to a reviewer or an implementer. It isn't, and now the spec says why, measured rather than asserted:

$ npm create flow-state-nonexistent-xyz123
npm error 404  GET https://registry.npmjs.org/create-flow-state-nonexistent-xyz123

npm create <name> resolves to the unscoped create-<name>. A scoped publish claims nothing outside its scope, so a scoped-only package leaves the headline command pointing at a package that does not exist. Decision 1 now carries that, and explicitly rejects the two-package shape — it would work, but nobody would ever be told to type the scoped form, so the alias exists only to be unused (tenet 3). One package, agreed, no argument needed.

Also added, because it is the one thing an implementer would get wrong by following convention correctly: this package's manifest name is the bare create-flow-state — the only unscoped package in the repo — and the directory being packages/create-flow-state/ does not by itself set the published name.

The correction going the other way: create-fsd-app is not ours. The brief I was given said the owner had acquired create-flow-state, create-fsd-app and flow-state-app, and my decision 1 repeated it as fact. Checking:

name registry
create-flow-state 404
flow-state-app 404
flow-state 404
fsdev 404
@flow-state-dev/cli 404
create-fsd-app 1.1.2 — keyready <vip.korchak@list.ru>, created 2024-10-18, a React/Vite starter

So FIX-1162's original finding was right and the later report that we had acquired the name does not survive checking. This changes nothing about the choice — create-flow-state is the name, and it is genuinely unpublished — but I have removed the false claim rather than carry it, and reframed the §12 note as "the epic's prose is stale on which name; FIX-1162 is not corrected on its facts."

On your caveat, implemented as directed. §12 now separates the two states explicitly rather than blurring them: verified — every relevant name 404s and nothing under this project has ever been published; asserted — that the name is ours. Worth stating plainly since it sharpens your point: npm has no reservation mechanism. A name is claimed by publishing, so "the owner holds create-flow-state" cannot be confirmed from outside until we publish it — and create-fsd-app is the cautionary case of a name this epic wanted being taken by someone else first. No fallback is designed, per your direction; a contingency would have spread through §5, §6, §7, §9 and §11 to hedge a question that gets answered before anything is built.

One thing I did not do, flagging it rather than acting: @flow-state-dev/* is unpublished too, and FIX-1159's printed commands assume a resolvable fsdev. That is a different question from this issue's one name — a bin name is not a package name — so §12 raises it for FIX-1162 to state which names the launch actually requires, rather than my guessing at scope that isn't mine.

New head: c67c063. Linear document and issue re-synced.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c67c063661

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md Outdated
Comment on lines +32 to +33
`npm create flow-state my-app` makes a directory, puts a working AI chat feature in it, and
leaves the developer looking at that feature streaming in their browser.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Align the one-command promise with the actual stopping point

The proposed command does not leave the developer viewing a streaming feature: the transcript in §5 stops after scaffolding and tells them to run npm run dev, while §10 likewise requires starting that command and interacting with the browser separately. This makes the headline outcome and acceptance path disagree, so either the scaffolder must start/open the app or the promised outcome should explicitly be a ready-to-run project rather than a visible result.

Useful? React with 👍 / 👎.

…ream

Codex flagged §2's "leaves the developer looking at the feature streaming"
against §5's transcript, which stops after scaffolding and prints `npm run dev`.
Offered two fixes: auto-start the app, or restate the outcome.

Neither taken — the mismatch is in the epic, not here, and the epic-agent is
folding it. Verified directly rather than inherited: the epic's §1 states the
Outcome as "in one step" (line 17) while its Proof for this issue says "the npx
command followed by the printed dev command" (line 57). The Proof is the precise
statement and was sharpened at epic review round 3, so the Outcome is the loose
half. This spec already matches the Proof — §5's transcript is the exact stopping
point and §10 measures from it.

Auto-start is explicitly ruled out in the note: create-next-app and create-vite
both stop and print the dev command, so adopting it would be scope growth bought
with a reviewer's phrasing. Recorded with the §1-Outcome-versus-§1-Proof mismatch
named so it does not come back a third time, and with the escape hatch pointed at
prose (one sentence in §2) rather than at scaffolder behaviour.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m

Copy link
Copy Markdown
Collaborator Author

@codex — real finding, but neither proposed fix is the right one, and the mismatch is not in this spec. Recorded in §13 (a1c1553) rather than folded.

Where the contradiction actually lives. Checked the epic directly rather than reasoning from this document:

  • epic §1 Outcome (line 17) — "a working AI feature streaming from a real model inside their own project … in one step"
  • epic §1 Proof for this issue (line 57) — "the npx command followed by the printed dev command yields a streamed model response"

Two lines in the same section disagreeing. The Proof is the precise one and was deliberately sharpened at epic review round 3, so the Outcome is the loose half — and it is the half being fixed. The epic-agent has it.

This spec already matches the Proof. §5's transcript ends after scaffolding and prints npm run dev; §10 measures from that point. So the design is not what's inconsistent — §2's one-sentence compression of it is echoing the epic's looser phrasing, and it stops echoing it when the epic lands.

On the first option — having the scaffolder start and open the app — no. create-next-app and create-vite both stop and print the dev command; that is the convention for this class of tool, and a scaffolder that seizes the terminal and opens a browser is a worse citizen in CI, in a container, and in someone's editor-integrated shell. Taking it would mean growing scope on the strength of a phrasing mismatch, which is the wrong direction of causation. §13 says so explicitly so it does not get proposed a third time.

On the second — restating the outcome — that is the right shape of fix, in the wrong document. Rewording §2 here while the epic still says "in one step" would leave the child tighter than its parent and invite the reverse finding next round. It goes upstream first; if §2 still reads as overclaiming afterwards, §13 points at the fix being one sentence of prose, never a behaviour change in the scaffolder.

For what it is worth, this is the third finding of yours on this PR that turned out to be pointing at something real one layer up rather than at the thing it landed on — the pin, the probe's exit status, and now this. That pattern is worth more than the individual catches.

New head: a1c1553.


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Outcome

Agreed—the review finding is valid, but the requested change does not belong in this spec.

  • The spec deliberately defines scaffolding as producing the project and printing the next command; its verification subsequently runs that command and validates the real application path. spec/FIX-548.mdL32-L39 spec/FIX-548.mdL525-L534
  • §13 now records the actual upstream contradiction between the epic’s broad Outcome and its more precise Proof, while noting that this spec already follows the Proof. spec/FIX-548.mdL693-L705
  • The note explicitly rejects auto-starting or auto-opening the application because that would unnecessarily expand scaffolder behavior, and confines any residual correction after the epic lands to one sentence in §2. spec/FIX-548.mdL707-L713

No additional changes were warranted: the working tree is clean at a1c1553e, which already contains the requested disposition. Therefore I did not create a redundant commit or follow-up PR.

Testing

  • ✅ git diff --check
  • ✅ git status --short --branch
  • ✅ git log -1 --oneline
  • ✅ nl -ba spec/FIX-548.md | sed -n '24,45p;480,535p;688,716p'

View task →

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a1c1553e8c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +118 to +120
local got_build; [ $build_status -eq 0 ] && got_build=pass || got_build=fail
echo " build: $got_build (expected $want_build)"
[ "$got_build" = "$want_build" ] || fail "$label: build $got_build, README claims $want_build"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Validate the expected build failure reason

When either intentionally failing .mts variant breaks for an unrelated reason—such as a shared route syntax error, dependency failure, or new Next.js regression—this reduces every nonzero build status to fail and accepts it as matching the documented result. The probe can therefore exit successfully without reproducing the specific TS5097 or module-resolution behavior used to justify the chosen config shape; assert the expected diagnostic for each failing variant rather than only the exit status.

Useful? React with 👍 / 👎.

Comment on lines +43 to +44
echo "AGENTS.md delimiters:"; grep -o 'BEGIN:[a-z-]*' AGENTS.md || echo " (none)"
echo ".gitignore env line:"; grep -n '^\.env' .gitignore || echo " (none)"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Make the scaffold discovery checks affect the result

When the pinned scaffolder stops creating AGENTS.md or its .gitignore loses the .env* rule, these commands only print the absence and leave RC unchanged. The later append can recreate AGENTS.md, and next dev can restore Next's block, so the probe may still exit 0 even though the spec cites these as verified scaffold facts; turn the discovery checks, including the claimed CLAUDE.md creation, into assertions that call fail.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dce7a2611f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md
Comment on lines +852 to +855
**Step 6 — add the dependencies, which is also the install.** Run the resolved package manager's
**add** command in the target directory, with the dependency set derived above as its arguments —
`npm install <pkg> …`, `pnpm add <pkg> …`, `yarn add <pkg> …`, `bun add <pkg> …`. **This is the
step that writes the dependency entries into `package.json`**, and it resolves them in the same

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Pin generated dependencies to compatible versions

When an older scaffolder is invoked after any FSD, provider SDK, or Zod release, these bare package names resolve the current registry versions rather than versions tested with the checked-in template. This is especially unsafe because .changeset/config.json has no fixed or linked FSD release group, so a pre-1.0 package can move independently and leave the generated project failing to build or run even though the exact create-next-app pin remains unchanged; include compatible versions in the add arguments while still letting the package manager author the manifest and lockfile.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
Comment on lines +392 to +395
> **The generated app refuses to serve its demo flow in production until real authentication is
> configured. Once it is, the app serves normally wherever it is deployed — container, platform,
> or bare host. In development it also binds to the local machine only, which is a development
> default the developer can change in one word.**

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep authenticated production hosts reachable

When a developer configures real authentication and self-hosts with the generated npm start, the hard-coded next start --hostname 127.0.0.1 from decision 8 remains in effect, so a reverse proxy, container, or remote client still cannot reach the app. The promise that authentication alone makes the app serve normally on a bare host is therefore false; either leave the production bind network-accessible behind the production authentication guard or tell users that they must also change scripts.start.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
app/page.tsx (replaced — the stock Next.js page)
Appended AGENTS.md (FSD section)
Wrote .env.local (OPENAI_API_KEY, already ignored by git)
Added 7 dependencies via npm (@flow-state-dev/*, @ai-sdk/openai, zod)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Report all eight generated dependencies

The exhaustive dependency rule at lines 772–781 contains eight direct dependencies—six @flow-state-dev/* packages, the selected provider SDK, and zod—but this required success transcript reports seven. Because the spec says every transcript line is emitted and the report is compared with the generated diff, a correct implementation must either misreport a successful scaffold or omit a required package; derive the displayed count or change it to eight.

Useful? React with 👍 / 👎.

claude added 3 commits August 19, 2026 01:09
…l, pin FSD versions, derive the dependency count

Three findings on dce7a26.

The epic withdrew `start` from theme 6 exception (c) and this spec had not
followed — the eighth restatement drift. Narrowing `start` is actively harmful:
"a platform deploy never runs next start" is false of Docker/Render/Railway/
Fly/Heroku/App Runner, and Next's -H carries no env binding, so a container
binds loopback and reads as dead. scripts.start now keeps create-next-app's
value byte for byte, which settles the finding that a self-hosted app could not
be reached.

The production refusal is not shipped. A POC ran executeServeCommand and found
the guard keys on bind address not environment, enforces whole-app not per-flow,
refuses a host-authenticated app as a false positive, and never runs on the Next
mounted route at all — verified independently: the symbol appears only under
packages/node and packages/cli/src/commands/serve.ts. The old wording named a
control we had not built. The product statement is withdrawn with it; four
versions were false, each derived from our own rules rather than measured.

§10 gains the mirror assertion — the built app is reachable from a non-loopback
address and scripts.start is unmodified — which asserts the absence of a
narrowing rather than the presence of a guard, so it needs no Q7 answer.

FSD packages in the add argument set now carry an exact version. changeset
config declares fixed:[] and linked:[], so they version independently and bare
names resolve whatever latest is rather than what the template was tested
against — while create-next-app stays exactly pinned, making the project look
reproducible when half of it is not. A fixed release group would collapse the
pin to one string; raised with FIX-1162 rather than decided here.

The transcript's dependency count is rendered from the add argv rather than
typed; it said 7 while the derived table required 8.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… claim

Residual sweep after d34dfa9. Withdrawing the scripts.start narrowing changes
the change-set arithmetic everywhere it is stated: four scaffolder-file changes
become three (§7's further-changes framing) and five become four (§5's
what-the-run-touched framing). Also removed the start row from the change
table, the production refusal from the flow-file and step-3 descriptions, the
engine-guard premise that described a control no longer specified, and the
follow-up asking whether the framework should own that guard — replaced by the
Q7 dependency. §10's script assertion now checks both directions: dev carries
the flag, start does not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
…d in the evolution log

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m

Copy link
Copy Markdown
Collaborator Author

@codex — all three folded in d34dfa9, a2dcb53 and 4552da7. This is a round, not a convergence — two of the three are direction-level.

Direction-level #1 — the production bind. Confirmed, and the fix is a withdrawal

You are right that next start --hostname 127.0.0.1 makes a self-hosted app unreachable, and the finding lands on a decision that had already drifted: epic theme 6 exception (c) was narrowed to dev only, and this spec had not followed. The epic's reason is stronger than the one you gave — narrowing start is not merely a promise mismatch, it is harmful: "a platform deploy never runs next start" is false of Docker, Render, Railway, Fly, Heroku and App Runner, and Next's -H carries no environment binding, so HOST=0.0.0.0 cannot override a hard-coded flag. The container binds loopback, health checks never connect, and the app reads as dead.

scripts.start now keeps create-next-app's value byte for byte. Of your two options, that is the first one, and it needs no "you must also change scripts.start" instruction because there is nothing left to change.

The production refusal is withdrawn too, and that is the larger half. A POC ran executeServeCommand — the function fsdev serve actually invokes — and every property the old wording rested on turned out to be false:

the old decision assumed what the code does
keyed on deployment/environment keyed on the bind address; no NODE_ENV check exists on the path
per-flow, so a correct flow keeps serving whole-app — a host resolver plus one inheriting flow refuses everything, naming only the inheriting one
configuring authentication lifts it no host-level configuration satisfies it; a host-authenticated app is refused as a false positive (with --allow-unauthenticated it binds and still rejects uncredentialed requests correctly — 500 without, 202 with)
it protects this template it never runs here. I verified independently of the POC: the symbol appears only under packages/node/ and packages/cli/src/commands/serve.ts, never in packages/next

So the decision named a control that does not exist and could not be described. Four successive product statements were false, and every one was produced the same way — by deriving behaviour from our own rules rather than measuring it, with the derivation never failing loudly. The statement is withdrawn rather than rewritten a fifth time; what a rail should do is epic §5 Q7.

§10 keeps the dev-bind assertion and gains its mirror: the built app is reachable from a non-loopback address and scripts.start is byte-identical to what the scaffolder wrote. That one asserts the absence of a narrowing rather than the presence of a guard, so it needs no answer from Q7 — and it is the check that would have caught this finding. The missing production assertion is recorded as a decision, not left as an oversight.

One hazard logged in §12 for whoever writes deployment docs: the sanctioned escape from the false positive is --allow-unauthenticated, and it disables the guard wholesale — a developer told to add it so their correct app can bind has silently switched it off for every flow they add later. The framework defect is filed separately.

Direction-level #2 — unpinned versions. Confirmed, and checked against the release process

.changeset/config.json declares "fixed": [] and "linked": [], so every FSD package versions independently, and pre-1.0 a minor is breaking by convention. Bare names resolve whatever latest is when a stranger runs the command — not what the checked-in template was built against — so one scaffolder release can pull engine and core from trains that were never built together.

The asymmetry is what makes it worse than an ordinary risk, and it is the part I would not have seen without the finding: this spec pins create-next-app exactly and argues at length that a range lets upstream drift reach users. That makes the generated project look reproducible while its FSD half is not pinned at all — and we ship the breaking changes.

FSD packages now carry an exact version in the add arguments, held in the same constant as the create-next-app pin and bumped with it behind a goal-check run. zod and the @ai-sdk/* package keep bare names. The manager still authors the manifest and lockfile, so decision 4's exception stays at one key. A caret was considered and rejected for the reason a range was already rejected for the scaffolder: it re-resolves on every invocation.

Not decided here: if the release process adopts a fixed group for @flow-state-dev/*, this pin collapses from N version strings to one and the changeset release keeps them consistent. That is a repo-wide publishing decision, so it is raised with FIX-1162 as a cross-issue note rather than a dependency — the exact pin works under either answer.

Implementer-level — the count, fixed derived

The transcript said 7 while §7's derived table required 8. Since §10 compares every emitted line against the generated diff, an implementation building from that transcript would have had to either misreport a successful scaffold or omit a package.

Fixed the second way you offered: the count and the list are rendered from step 6's add argument set, never typed. The 8 in the transcript is now labelled as what that rendering produces for an OpenAI scaffold — an illustration of a computed value, not a number this document maintains. A literal would pass this round and drift at the next change to the set.

This one is the class in miniature, and it is worth naming as such: a number stated in one place, derived in another, with nothing keeping them equal. That is exactly the recorded-but-not-enforced shape §13 now opens with — the FIX-1160 edge, the dependency set, sub-PR a's prerequisites, and now this. It is the smallest worked example in the document, which makes it the most useful one: the fix is not to correct the number but to remove the second place it was stated.


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Summary

  • Corrected the generated success transcript so it now describes only the development loopback bind and no longer promises a withdrawn production refusal. This aligns the printed guidance with the spec’s explicit decision to preserve scripts.start and ship no production guard. spec/FIX-548.mdL326-L332 spec/FIX-548.mdL595-L600
  • Confirmed the FSD dependencies use exact versions in the package-manager add arguments, while provider SDKs and Zod remain unpinned as specified. spec/FIX-548.mdL863-L881
  • Confirmed the dependency count and displayed list are derived from the actual add arguments, with the OpenAI transcript correctly illustrating eight dependencies. spec/FIX-548.mdL585-L586 spec/FIX-548.mdL639-L648
  • Committed the follow-up as e13487a3 (spec(FIX-548): align printed security guidance with withdrawal).
  • No changeset was added because this is a spec-only correction with no publishable package impact.
  • A follow-up pull request could not be opened because the required make_pr tool is unavailable in this environment; the repository also has no configured remote and gh is unauthenticated.

Testing

  • ✅ git diff --check
  • ✅ ! sed -n '570,610p' spec/FIX-548.md | rg 'will not serve in production|until you configure authentication'
  • ✅ ! rg -n 'next start --hostname 127\\.0\\.0\\.1' spec/FIX-548.md
  • ✅ git show --format= --check d34dfa9^..HEAD
  • ✅ test "$(git rev-parse HEAD^)" = "4552da7fab334f0776c5b959987a4850c0f3bca1"
  • ✅ git status --short --branch
  • ⚠️ gh auth status — GitHub CLI is not authenticated, and no Git remote is configured.
  • ⚠️ make_pr — unavailable in the provided toolset, so the required follow-up PR could not be created.

View task →

claude added 3 commits August 19, 2026 01:14
…ecord the credential asymmetry

Cross-spec check against FIX-1159 at 4a110aa and the epic at 673fcd5.

FIX-1159 does put a per-flow FSD_DEMO_TOKEN on its demo flow, but that is a
different artifact: it writes flows/hello/flow.mts, this template writes
src/flows/chat/flow.ts, and FIX-1159's Non-goals disclaim the greenfield
template in every part. Epic theme 8's matrix — the statement of record — gives
greenfield mounted-route the dev bind and explicitly no credential, because the
demo is a browser page and any token it holds is readable from that page. Both
descriptions are true of their own flow. §12 now says so with the matrix, since
two specs describing "the demo flow" with opposite postures is how a reader
believes the wrong one.

§12 also gains the plain deployment description: dev binds loopback, production
binds wherever Next binds, and the demo flow accepts any caller — so a deployed
generated app runs model calls for anyone who finds it, billed to the
developer's key. Description, not alarm; it is what Q7 is deciding.

Also fixes a defect of the class §13 opens with, in my own text: decision 8 said
the description was "in §12" while §12 contained none. A cross-reference to
content that does not exist is a requirement nothing enforces. Logged in place
rather than quietly corrected.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… printed transcript

Eleventh instance of the shape, and the first on a withdrawal reaching printed
output. The generated success transcript still told the user "This app serves on
127.0.0.1 only, and will not serve in production until you configure
authentication." Both halves became false when decision 8 withdrew the start
narrowing and the production refusal. Replaced with the two things that are
true: npm run dev binds loopback, and the demo flow accepts any caller.

The larger finding is where that text lives. It is inside FIX-1159's canonical
next-steps block, which this package embeds verbatim under a normalized equality
assertion — so a withdrawn promise surviving in canonical would be re-shipped to
every user of the scaffolder, with the drift check actively preventing the
shipper from correcting it. §12 now carries that to FIX-1159 as a required
correction rather than a suggestion.

§13's note is widened to cover withdrawals, which it did not. A rule about
requirements being enforced somewhere does not cover promises that must stop
being made in every place they appear, and this epic has now proven the
withdrawal direction four times. Both directions are stated, with the
embedded-under-equality case called out as the one a shipper cannot complete
from its own side.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m
… log

Residual from the withdrawal sweep. An evolution entry still read "Decision 8
now carries the corrected statement verbatim as the wording to use" and quoted
a statement that is false and withdrawn — prescriptive phrasing in a historical
log. Marked superseded with a pointer to decision 8, and left in place rather
than rewritten, since a run of corrections each looking final is the argument
for withdrawing the statement rather than fixing it again.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m

Copy link
Copy Markdown
Collaborator Author

Folded in 64227dd, 28c2d08 and eb38dea — part of the current round, not a new one. Two things: the transcript finding, and the cross-spec credential question.

The transcript still promised the refusal I withdrew — confirmed, and the mechanism makes it worse than a stale line

The generated success transcript told the user:

This app serves on 127.0.0.1 only, and will not serve in production until you configure authentication.

Both halves are false. scripts.start keeps create-next-app's value, so the app does not serve on loopback only; and no production refusal ships. Replaced with the two things that are true — npm run dev binds loopback, and the demo flow accepts any caller, so configure authentication before deploying.

The part that is bigger than the wording: that text lives inside FIX-1159's canonical next-steps block. This package embeds it verbatim and §10 asserts normalized equality over the whole block. So a withdrawn promise surviving in canonical would be re-shipped to every user of the scaffolder, with the equality check actively preventing the shipper from correcting it — the mechanism built to stop drift would pin a false security claim in place. §12 now carries this to FIX-1159 as a required correction, not a request, because a shipper cannot fix it from its own side by construction.

§13's note did not cover withdrawals. It does now

You were right to ask. The note read "a requirement recorded in one section and enforced by no other" — which says nothing about a promise that must stop being made everywhere it appears. That direction has now cost this spec four times:

withdrawn where it survived
scripts.start narrowing decision 8, the change table, §8, §10 — a full round
the production refusal the flow-file description, step 3, a §12 premise, a follow-up
the same refusal again the generated success transcript — the surface a user reads
the §12 description decision 8 pointed at a §12 that did not contain it

The rule is now stated in both directions. Additions: name the artifact that will execute the requirement. Withdrawals: enumerate every surface that restates the claim before declaring it withdrawn — decision, tables, transcripts, printed output, tests, and anything embedding it verbatim downstream. A promise withdrawn in one section and still printed in another is not withdrawn, and it is worse than before, because the document now disagrees with itself and the surviving copy is the one a user reads.

One clause is specific to this case and generalises past the document: when you withdraw a claim, check whether any downstream artifact embeds it under an equality constraint. That is where a withdrawal cannot be completed from your own side.

A residual from my own sweep, logged rather than quietly fixed: an evolution entry still read "Decision 8 now carries the corrected statement verbatim as the wording to use" and quoted a statement that is false and withdrawn — prescriptive phrasing in a historical log. Marked superseded, left in place, because four corrections each looking final is the argument for withdrawing the statement rather than fixing it a fifth time.

The cross-spec question: distinct artifacts, and the asymmetry is a rule

Verified against FIX-1159 at 4a110aa and the epic at 673fcd5, not from memory.

They are different files. This template writes src/flows/chat/flow.ts; the brownfield skill writes flows/hello/flow.mts. FIX-1159's Non-goals disclaim "the greenfield command and its template in every part", and its decision 7 justifies the token by a condition that is brownfield-specific — "the run adds an endpoint to a server the developer already exposes on every interface". Greenfield does not have that condition: we author scripts.dev and bind it.

The asymmetry is epic theme 8's matrix, which is the statement of record:

loopback bind credential why
greenfield, mounted-route (this issue) dev only; production unresolved, §5 Q7 no the demo is a browser page, so any token it holds an attacker reads from the same page
brownfield, mounted-route no — their dev script yes the only control available
brownfield, second-process yes — our printed fsdev serve --host 127.0.0.1 yes both: we author the start command and ship no browser client

The generalisation cuts across greenfield/brownfield rather than along it: a path gets the bind when we author the command that starts the server, and the credential when the demo ships no browser client to leak it. This template authors scripts.dev and ships a chat page — which is exactly why it has the first and not the second.

So both statements are true of their own flow. §12 now says so explicitly, with the matrix, because two specs in one epic describing "the demo flow" with opposite postures is how a reader believes the wrong one.

And what a developer actually gets, in the spec that ships it

§12 now states it as description rather than alarm — dev binds loopback; production binds wherever Next binds; the demo flow accepts any caller, so a deployed generated app is an endpoint that runs model calls for anyone who finds it, billed to the developer's provider key, with no tenant boundary. git check-ignore keeps the key out of version control, which is a different problem from keeping it out of a stranger's requests. What closes it is configuring real authentication. That is what §5 Q7 is deciding, and it should be legible here rather than only in the epic.

Process note

Taken, and applied here: the fix for this finding was committed in an environment that could not push, so I treated the report as a finding only and re-derived the edit from the description. That turned out to matter — the described fix is the transcript line, but re-deriving it surfaced that the line is canonical text owned by another issue, which is the constraint that makes it a cross-issue correction rather than a local one.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eb38deaaa4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md Outdated
**The FSD packages in that argument set carry an exact version; the others do not.** `npm install
@flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same
constant file as the `create-next-app` pin and bumped with it as scheduled maintenance behind a
goal-check run. `zod` and the `@ai-sdk/*` package keep their bare names.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Pin Zod to the core-compatible major

When the bare zod dependency resolves to Zod 4, the generated flow imports a v4 schema and passes it to @flow-state-dev/core, whose packages/core/package.json still depends on zod ^3.25.76 and exposes v3 ZodTypeAny in its block APIs. A v4 z.object(...) is incompatible with that type (TS2740), so the generated Next project can fail its build immediately. Fresh evidence beyond the earlier dependency-pin comment is that this revision now explicitly leaves Zod floating; pin a compatible Zod 3 release or first make the framework's schema boundary support v4.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
Comment on lines +884 to +886
**The FSD packages in that argument set carry an exact version; the others do not.** `npm install
@flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same
constant file as the `create-next-app` pin and bumped with it as scheduled maintenance behind a

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Version each independently released package separately

After any release where the FSD packages have different versions, this single <v> requests an incorrect or nonexistent version for at least one of core, engine, next, react, CLI, or DevTool. The following paragraph confirms that .changeset/config.json has no fixed or linked group, so these packages version independently. Fresh evidence beyond the earlier bare-dependency finding is that the proposed pinning fix collapses those independent versions into one constant; use a tested per-package version map or make fixed-group adoption a prerequisite.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
Comment on lines +884 to +885
**The FSD packages in that argument set carry an exact version; the others do not.** `npm install
@flow-state-dev/core@<v> @flow-state-dev/engine@<v> …` — one version string, held in the same

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Save the dependency pins without range prefixes

When npm or pnpm performs this add, specifying @pkg@<v> selects that exact version for the current install but does not necessarily persist an exact manifest entry: npm install --help lists -E|--save-exact while the default configuration is save-exact=false with save-prefix=^, and pnpm add --help describes -E as “Install exact version.” A later lockfile refresh can therefore drift despite the spec's pinning guarantee. Fresh evidence beyond the earlier pinning comment is that the new add command omits the package-manager-specific exact-save option; include it or verify that the written manifest contains literal versions.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md Outdated
| `-y` with no key in the environment | Scaffold completes. `.env.local` carries the empty variable line, and one line before the next-steps block says the key is still needed. Do not refuse — an unattended scaffold is legitimate. **There is no key flag** (§5), so `-y` and an unset variable is the only way to reach this state, and it is CI's path rather than the goal check's. |
| The developer runs `npm run dev` and `fsdev dev` together | Both open the same development file store; concurrent writes to one session can each be accepted. Tolerable for a development default, and the next-steps block says to drive one at a time (§12 raises the wording with FIX-1159, which authors the block). |
| The developer wants to reach the app from another device | `npm run dev` binds `127.0.0.1` (decision 8), so it will not connect. This is the intended behaviour, not a bug: the flow is unauthenticated and the bind is the only control. The fix is theirs to make — remove `--hostname 127.0.0.1` from `scripts.dev`, a one-word edit in a file we wrote seconds ago — and they should understand what they are removing. |
| The developer deploys the generated app as-is | The mounted route **refuses before any model invocation**, with an error naming the missing authentication (decision 8). Not a warning, and not a 200 with an error body. |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Delete the withdrawn production-refusal row

When an implementer follows this deployment row, they must add an authentication refusal that the current design explicitly excludes: decision 8 says no production rail ships, the generated-flow contract says it declares no production refusal, and §10 deliberately omits that assertion pending Q7. Fresh evidence after the earlier guard and bind comments is that this revision now expressly withdraws the refusal while this row still mandates it; remove or rewrite the row so the build plan has one production contract.

Useful? React with 👍 / 👎.

Comment on lines +184 to +186
node -e "import('./$cfg').then(m=>{
if(m.default.marker!=='config-module-loaded'){console.error('WRONG MODULE');process.exitCode=3}
}).catch(e=>{console.error('IMPORT THREW: '+e.message);process.exitCode=3})" > import.log 2>&1

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Neutralize warning suppression before probing imports

When the caller has NODE_NO_WARNINGS=1 or NODE_OPTIONS=--no-warnings, this child inherits it, so the expected MODULE_TYPELESS_PACKAGE_JSON diagnostic is suppressed and the no-type-field variant is classified as clean. The probe then exits 1 and reports a documented Node behavior as disproved even though the environment merely hid the evidence, violating the README's exit-1/exit-2 contract. Clear warning-suppression variables for this invocation or classify such an environment as cannot-verify.

Useful? React with 👍 / 👎.

…with a per-package map, assert the written manifest

Five findings on eb38dea, three of them defects in the pinning fix from the
previous round.

Leaving zod floating aimed the risk at a specific type boundary: core depends
on zod ^3.25.76 and types its public block surface as v3 ZodTypeAny, so a bare
zod resolving to v4 fails next build on a type error before any model call.
Pinned to a compatible v3 range; whether core should accept v4 is raised as a
separate framework question.

One version placeholder cannot version six independently released packages —
changeset config declares fixed:[] and linked:[]. Replaced with a per-package
version map. A fixed release group would collapse it to one entry; that is
FIX-1162's work and is a note, not a dependency, since the map is correct
either way.

add pkg@1.2.3 does not persist 1.2.3: npm defaults to save-prefix=^ and pnpm
needs -E. The exact flag is specified and §10 now asserts the written manifest
rather than the argv, which also catches a changed default and a lockfile
refresh.

§9's deployment row still mandated the withdrawn production refusal — the third
surface for that withdrawal and the fourth table row across all of them. §13's
note now names tables and matrices specifically, since a row states a claim in a
section organised by a different question and a phrase search never finds it.

probe.sh cleared NODE_NO_WARNINGS/NODE_OPTIONS for the import check: inherited
suppression made a true claim about Node report as disproved. Second application
of the standing unfreeze clause, applied without re-arguing it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m

Copy link
Copy Markdown
Collaborator Author

All five folded in 48cc886. Three of them were defects in the pinning fix from the previous round, which is the fourth consecutive time a fix has produced the next finding.

P1 — floating Zod. Confirmed, and the shape is worse than "unpinned"

Verified: packages/core/package.json depends on zod: ^3.25.76, and core types its public block surface as v3 ZodTypeAny — packages/core/src/types/block.ts imports it for stateSchema and the connector targets, types/agent.ts for outputSchema. The generated flow imports z directly and hands its z.object(...) to exactly those APIs. A bare zod resolves to Zod 4, whose schemas are not assignable, so the generated project fails next build on a type error before it ever reaches a model — the headline outcome broken on the first command.

The framing in the finding is the part worth keeping. The previous round pinned the FSD packages and left Zod floating deliberately. That did not leave a general risk in place; it aimed the remaining risk at the one type boundary the generated flow crosses on every run. A partial fix that removes the safe cases and keeps the dangerous one is worse than no fix, because the surviving hazard now looks considered.

zod is pinned to a compatible v3 range. Whether core's schema boundary should accept Zod 4 is a real framework question and I have not answered it here — taking your offer to treat it separately, since this template has to work against the framework as it ships and pinning v3 costs nothing if the boundary later widens.

P2 — one <v> for six independently released packages. Confirmed

.changeset/config.json declares "fixed": [] and "linked": [], so core, engine, next, react, cli and devtool each move on their own. After any release where two differ, a single placeholder requests a version that is wrong for one and very likely nonexistent for another — the scaffolder fails its own install.

Replaced with a per-package version map, one entry each, rendered into the add arguments. I took your first option: the map is not a workaround for a missing release group, it is what independent versioning requires. A fixed group would collapse it to one entry — that is FIX-1162's release work, and it is recorded as a cross-issue note rather than a dependency, because the map is correct under either answer. I have deliberately not made this spec wait on it.

P2 — add pkg@1.2.3 does not persist an exact entry. Confirmed

npm defaults to save-exact=false with save-prefix=^, so it writes ^1.2.3; pnpm behaves the same without -E. The pinning guarantee was prose while the manifest said ^1.2.3, and the drift would arrive on the developer's next install.

I took your second option, and it is stronger than the flag for the reason you gave. The add command carries the manager-appropriate exact flag, and §10 asserts the written manifest: every FSD entry and zod is a literal version with no range operator. That catches a wrong flag, a manager whose default changes, and a later lockfile refresh re-resolving a caret — none of which an argv assertion sees. zod is asserted by name, because its drift is a build break rather than a version skew.

P2 — the deployment row still mandated the refusal. Confirmed, and your question about tables is right

§9's row instructed an implementer to build the production refusal that decision 8 withdrew, the generated-flow contract says is not declared, and §10 deliberately omits pending Q7. Third surface for that one withdrawal, and the fourth table row across all of them.

You asked whether §13's note needs to name tables specifically. Yes — and the tally is the argument. Four of five withdrawal residuals were a row, not a sentence:

withdrawn surviving surface kind
scripts.start narrowing decision 8, change table, §8, §10 table row
production refusal file-table row, step 3, §12 premise, follow-up table row
same refusal the generated success transcript printed output
the §12 description a cross-reference to content that did not exist cross-reference
same refusal, third time §9's deployment row table row

The mechanism is now stated: prose restates a claim in language a reader recognises as a restatement, while a row states it as a fact, compressed, in a section organised by a different question — §9 by failure case, §7's file table by file, neither by which control ships. So a search for the withdrawn wording never finds it, because the row never used that wording. The rule now says to walk every table and matrix by reading the rows. I ran that sweep on this revision; the remaining rows are consistent.

P2 — probe warning suppression. Applied under the standing clause, not re-argued

Confirmed and fixed: the import check reads stderr to decide whether Node's documented MODULE_TYPELESS_PACKAGE_JSON warning appeared, and suppression is inherited — under NODE_NO_WARNINGS=1 or --no-warnings the no-type-field variant emits nothing, classifies as clean, and the probe exits 1: disproved on a true claim. Both variables are cleared for that invocation.

You are right that the rule already decided this, so I applied it and said so rather than re-litigating: it is under-reporting, not over-assertion, and documenting it would again mean telling a reader a red result might not mean what it says.

Two instances is enough to state the shape, and the README now carries it: this probe reads its evidence from process output, and process output is environment-dependent. Any future check that decides a claim from stdout/stderr clears whatever suppresses the signal it reads, or classifies the environment as cannot-verify (2).

The two dependencies

Both understood and neither anticipated. The withdrawn promise in FIX-1159's canonical block stays routed there as a required correction — this spec cannot close it from its own side. And everything reading "pending Q7" stays pending; nothing here assumes an answer, and §9's deployment row now says explicitly do not implement a production refusal before Q7 answers, since that row is where an implementer would otherwise pick it up.


Generated by Claude Code

Spec approved. Per the owner's direction, no further review rounds. The Zod pin
landed in 48cc886 as the one finding that would break an implementer on day one:
core depends on zod ^3.25.76 and types its public block surface as v3
ZodTypeAny, so an unpinned zod resolving to v4 fails next build before any model
call.

The remaining four findings are recorded in §13 as short implementer notes
rather than further spec surgery: the version map versus a fixed release group,
asserting pinning on the written manifest rather than the argv, the standing
prohibition on building a production refusal before Q7 answers, and the probe's
environment-dependent evidence.

No surviving instruction to build a production refusal remains anywhere in the
document; §9's deployment row states the prohibition rather than annotating a
withdrawn mandate.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UVQxJiUzAQfecJzfvyqN4m

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

# A section that is already malformed cannot speak to survival either way. That is
# "could not verify" (2), never "the claim is false" (1).
case "$FSD_BEFORE" in *"$FSD_E"*) ;; *) echo " FSD section malformed before next dev — CANNOT VERIFY"; exit 2;; esac
case "$NXT_BEFORE" in *"$NXT_E"*) ;; *) echo " next's block malformed before next dev — CANNOT VERIFY"; exit 2;; esac

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve mismatches for a missing Next agent block

When the pinned create-next-app stops writing its nextjs-agent-rules block, the earlier assertion sets RC=1, but the empty NXT_BEFORE value reaches this branch and immediately exits 2. A malformed block with a missing end marker follows the same path. Both cases disprove the README's asserted scaffold shape rather than making the environment unverifiable, so this masks the upstream regression the probe is intended to detect; retain exit 1 for absent or malformed scaffolder output.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md
Comment on lines +888 to +893
```
npm install --save-exact \
@flow-state-dev/core@<core> @flow-state-dev/engine@<engine> \
@flow-state-dev/next@<next> @flow-state-dev/react@<react> \
@flow-state-dev/cli@<cli> @flow-state-dev/devtool@<devtool> \
@ai-sdk/openai@<sdk> zod@<zod>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Install developer tooling as dev dependencies

When a generated app is packaged for production, this ordinary npm install writes @flow-state-dev/cli and @flow-state-dev/devtool into dependencies, so production-only installs cannot omit their CLI, UI assets, and transitive packages. The dependency table establishes that these two packages exist solely for the printed local-development commands, while the generated server imports neither; add them separately as exact dev dependencies so deployments do not carry development tooling.

Useful? React with 👍 / 👎.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-31T22:58:46.921986Z 071e3e9 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

# `fail`, reporting exit 1 (claim disproved) for a true claim, which is the one
# direction of wrongness that trains a reader to ignore a red result.
git init -q . 2>/dev/null || { echo " git init failed — .gitignore claim CANNOT VERIFY"; exit 2; }
if git check-ignore -q .env.local; then

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Isolate the ignore check from global Git rules

When the caller's core.excludesFile contains .env.local, git check-ignore succeeds even if the scaffold has no project-owned ignore rule; git check-ignore -v reproduces this while identifying the global file as the source. The probe can therefore keep passing after create-next-app drops its rule, falsely supporting the README/spec premise and allowing the eventual credential step to omit a durable local entry. Neutralize global excludes for this assertion or verify that the verbose match comes from the scaffold.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md
Comment on lines +246 to +248
*Not the package's `engines`.* This floor is what the **generated app** needs, checked against
the Node actually running the command. The scaffolder's own `engines` stays at the repo-wide
`>=22`; §9 records why narrowing that is a separate mistake.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Persist the runtime floor in the generated app

When a project is scaffolded on Node 22.18+ and later cloned or deployed on Node 22.0–22.17, the one-time scaffolder check no longer runs, the FSD packages' >=22 engines still admit that runtime, and the printed CLI commands fail to import fsdev.config.ts. The current revision addresses the earlier runtime-floor issue only during creation; keep the scaffolder's own engine range unchanged, but add node >=22.18 to the generated app's manifest so its stated requirement travels with the project.

Useful? React with 👍 / 👎.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md
Comment on lines +91 to +94
2. **One template ships: the Next.js chat app — conditional on a supported minimal-project path
existing for backend developers.** *This reverses epic theme 2, it is the ask on this PR, and
this spec asserts no answer to it — see the framing below and epic §5 Q6, which is open and
blocks implementation.*

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Apply the resolved one-template decision to the spec

Fresh evidence beyond the earlier option-B comment is the PR description’s explicit declaration that Q6 is answered with one Next.js starter and the spec is closed, while this decision still marks Q6 open and implementation-blocking here and again in §§3 and 12. An implementer following the spec would therefore wait for an already-made decision or reopen the discarded two-template branch; make decision 2 unconditional and remove the stale ask/open-question language.

AGENTS.md reference: AGENTS.md:L58-L58

Useful? React with 👍 / 👎.

# variant emits nothing, classifies as `clean`, and the probe reports a TRUE
# claim about Node as DISPROVED — the same false-disproof direction as the
# `git init` case, from a different cause. Cleared for this invocation only.
NODE_NO_WARNINGS= NODE_OPTIONS= \

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Clear redirected Node warnings before classifying the import

Fresh evidence after the earlier warning-suppression fix is Node’s separate NODE_REDIRECT_WARNINGS environment variable, which this invocation still inherits. node --help describes the corresponding option as “write warnings to file instead of stderr”; with this variable set, the expected MODULE_TYPELESS_PACKAGE_JSON warning goes to that file, import.log remains empty, and the no-type-field variant is misclassified as clean, causing exit 1 for a true claim. Clear NODE_REDIRECT_WARNINGS as well or classify that environment as cannot-verify.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md

| file | what it is |
|---|---|
| `fsdev.config.ts` | default-exports `createFlowState({ flows, modelResolver, stores })`. **`createFlowState` and the filesystem store factory both come from `@flow-state-dev/engine`, not `core`** — see the dependency set below. Registers the demo flow explicitly; **statically imports the chosen provider's factory and passes a pre-built `createModelResolver({ providers: { … } })` as `modelResolver`, with no intents** (decision 5); and declares FIX-1159 decision 5's development file store, qualified as such |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Ignore the generated filesystem store

Once the user sends a message through the generated app or a printed CLI command, this development store writes session and request data under the local store directory (conventionally .fsdev/data), but the pipeline only verifies an ignore rule for .env.local; create-next-app cannot supply an FSD-specific ignore rule. Consequently, a normal git add . can commit chat contents and execution state—the repository itself avoids this with **/.fsdev/** in its root .gitignore. Add the generated store path to the scaffold's ignore rules and verify it with git check-ignore alongside the credential check.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md

| package | why it is in the set — derived from | pnpm-only? |
|---|---|---|
| `@flow-state-dev/engine` | `fsdev.config.ts` imports **`createFlowState`** and **`createFilesystemStores`**, both exported from `engine` (`packages/engine/src/index.ts`), not from `core` | **yes** |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Use the filesystem store adapter in generated configs

Following this dependency/config contract makes every generated app wire createFilesystemStores(...), which returns a flat StoreRegistry, into createFlowState({ stores }); that option instead requires named profiles containing StoreAdapter values with capabilities and resolve. The generated config therefore fails typechecking (or store resolution if forced through). Specify filesystemStores(...) and the required profile/slot wrapper instead.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md
| Case | Expected |
|---|---|
| `.env.local` is about to be written | Ask git whether it would ignore that exact path (`git check-ignore`), never whether `.gitignore` contains a rule that looks right. In a fresh `create-next-app` scaffold the answer is already yes (verified), so this is normally an assertion rather than a write — but it is the assertion the credential stop rests on, so it is made against the path, not the text. |
| The ignore entry cannot be established | **Stop before the key is written.** The scaffold stays on disk and is left usable; print what is missing, the one line to add to `.gitignore`, **and the two remaining steps by name** — write the key into `.env.local`, then run the install. Never write the key "and warn" — the warning scrolls away and the credential does not. **The recovery is complete because the `AGENTS.md` section already landed in step 4** (§7); had the append still been last, this stop would have left the developer a project silently missing canonical text they cannot author. |

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Print the dependency-add command on credential stops

When the ignore check cannot be established, execution stops before step 6, so the manifest still has none of the FSD dependencies. Telling the developer merely to “run the install” can lead to npm install, which installs only the existing create-next-app manifest and leaves every generated FSD import unresolved; rerunning the scaffolder is also rejected because the target is now nonempty. Print the full versioned package-manager add command and package list here, as required for the step-6 failure path.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md
Comment on lines +1055 to +1058
7. **The printed next-steps block** — FIX-1159's canonical block embedded verbatim, rendered for
the resolved package manager and the `mounted-route` topology. *Test:* normalized equality over
the whole block including the `second-process` branch this package never renders; every printed
command runs. *Depends on:* 6, **and FIX-1159's block existing** — see §12.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve next-step output on recoverable failures

Step 7 is the only point that prints the canonical dev, DevTool, and CLI commands, but both recoverable stops occur in steps 5 and 6 before reaching it. Even after the developer follows the recovery instructions and finishes the key or dependency work, the nonempty target prevents rerunning the scaffolder, so this package never performs one of the five jobs it explicitly owns. Include the next-steps block in those recovery paths or provide a resumable way to emit it.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md
Comment on lines +689 to +691
**Unattended use is still legitimate and still works** — `-y` with the provider's variable already
exported produces a complete project without a prompt. What is unsupported is a key on the command
line.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Test unattended scaffolding with an environment key

This promises that -y plus the selected provider's environment variable produces a complete unattended scaffold, but the goal runs deliberately remove provider keys and the CI list tests only -y with no key. An implementation that never reads the environment and always writes an empty value would therefore satisfy every specified check while breaking this advertised automation path. Add coverage that exports each supported provider variable, runs with -y, and verifies the resulting credential and usable scaffold.

Useful? React with 👍 / 👎.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread spec/FIX-548.md
every addition): §6 is mostly about keeping the file list short and refusing surface — including a
`--template` flag with one legal value.

### 6. Decisions & rules — the sign-off surface

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Limit the sign-off surface to three outcome decisions

When the owner reaches the approval gate, this section asks them to certify eight decisions across roughly 4,200 words, including implementation mechanics such as module extensions, provider wiring, dependency handling, and Git commands. The repository's spec template caps this surface at three outcome-shaping calls; move engineer-owned mechanics to Part II so approval is not ambiguous about which product decisions the owner actually made.

AGENTS.md reference: AGENTS.md:L54-L58

Useful? React with 👍 / 👎.

grep -E "error TS|Module not found|Failed to|Compiled successfully|Route \(app\)|/api/flows" build.log | head -4 | sed 's/^/ /'
local got_build; [ $build_status -eq 0 ] && got_build=pass || got_build=fail
echo " build: $got_build (expected $want_build)"
[ "$got_build" = "$want_build" ] || fail "$label: build $got_build, README claims $want_build"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Classify environmental build failures as inconclusive

When next build is killed by an OOM, runs out of temporary-disk space, or otherwise fails for an environmental reason, this branch records a mismatch and the probe exits 1 (“claim disproved”) rather than 2 (“could not verify”). The later diagnostic check only records another mismatch when the expected route output is absent, so infrastructure failures violate the README's load-bearing exit-status contract; recognize such failures as inconclusive instead of treating every nonzero build as evidence against the documented variant.

Useful? React with 👍 / 👎.

Comment thread spec/FIX-548.md

---

## Spec evolution

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Collapse the superseded spec history

When an implementer searches this artifact for a behavior or decision, the uncollapsed 381-line evolution ledger exposes thousands of words of superseded—and sometimes explicitly false—designs alongside the current contract, increasing the chance that stale instructions are followed. Git and the PR already preserve this history; keep the current requirements visible and place any necessary provenance in a collapsed section as required for human-facing artifacts.

AGENTS.md reference: AGENTS.md:L217-L221

Useful? React with 👍 / 👎.

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

1 similar comment
@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

1 similar comment
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 071e3e915c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants